home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / utils / rtrac800 / rtrace.lst < prev    next >
File List  |  1992-09-08  |  19KB  |  527 lines
  1.  
  2.                                                        RTRACE(1G)
  3.  
  4. NAME
  5.      rtrace - ray tracing program
  6.  
  7. SYNOPSIS
  8.      rtrace [options] scene image [>log]
  9.  
  10. AUTHOR
  11.      Antonio Costa, INESC-Norte, 1989 1992
  12.  
  13. DESCRIPTION
  14.      rtrace command performs ray tracing from a SFF text file
  15.      which must describe a scene with objects, lights, surface
  16.      definitions, textures, etc.  This scene file must be in the
  17.      appropriate format, as described bellow.
  18.      Basically, ray tracing is an algorithm for the creation of
  19.      realistic images from the geometry and attributes of
  20.      objects, lights, etc.  This ray tracer supports several
  21.      types of objects (sphere, box, bicubic patch, cone,
  22.      cylinder, polygon, triangle and text), CSG and list opera-
  23.      tions, different light types, reasonable surface defini-
  24.      tions, lots of textures, several anti-aliasing schemes,
  25.      depth of field, stereoscopic image creation and so on...
  26.  
  27. OPTIONS
  28.      [wimage-width] [himage-height]
  29.      The parameters image-width and image-height define the image
  30.      size. Defaults are 256x256.
  31.  
  32.      [Aaliasing-threshold]
  33.      [Sshading-threshold]
  34.      [Tambient-threshold]
  35.      The parameters aliasing-threshold (pixel supersampling),
  36.      shading-threshold (shading rays propagation) and ambient-
  37.      threshold (ambient rays distribution caching) control the
  38.      image quality (0-best, 1-poor). Defaults are 0.05, 0.01 and
  39.      0 (no ambient threshold). Good ranges are 0.1-0.03, 0.01-
  40.      0.001 and 0.01-0.00001, respectively.
  41.  
  42.      [aantialiasing-mode]
  43.      The parameter antialiasing-mode chooses adaptive supersam-
  44.      pling antialiasing (0-default), semi-adaptive supersampling
  45.      antialiasing (1) or normal supersampling antialiasing (2-
  46.      should be used with nonzero focal apertures).
  47.  
  48.      [Bmaskfile]
  49.      The parameter maskfile creates a file with a background
  50.      mask, suitable for mixing images (it is like an alpha chan-
  51.      nel).
  52.  
  53.      [ccluster-size]
  54.      The parameter cluster-size controls the enclosing of objects
  55.      (number of grouped objects per cluster) in the object
  56.      hierarchy. Use a low value for sparse scenes, a high value
  57.      for dense scenes (4-default).
  58.  
  59.      [dambient-levels]
  60.      The parameter ambient-levels defines the number of shading
  61.      levels (shading tree depth) in which ambient lighting
  62.      calculations will be done through ray distribution (0-
  63.      default, ie, no ray distribution). Use low values!
  64.  
  65.      [Dambient-samples]
  66.      The parameter ambient-samples defines the maximum number of
  67.      distributed rays to be used in ambient lighting calculations
  68.      (16-default). Again, use with care.
  69.  
  70.      [iintersect-mode]
  71.      The parameter intersect-mode chooses, in adaptive supersam-
  72.      pling antialiasing, between testing all scene objects (1) or
  73.      only the objects found at the pixel corners and inside (0-
  74.      default; this greatly reduces CPU time, but with very small
  75.      objects, it sometimes fails).
  76.  
  77.      [Iintersect-adjust-mode]
  78.      The parameter intersect-adjust-mode avoids some problems
  79.      with invalid self-intersections (1) (0-default).  Scenes
  80.      with text objects should be traced with this parameter equal
  81.      to 1.
  82.  
  83.      [jjittering-mode]
  84.      The parameter jittering-mode chooses jittered sampling (1)
  85.      or not (0-default). Sometimes, activating it produces better
  86.      images from scenes with small tricky details.
  87.  
  88.      [llighting-mode]
  89.      The parameter light-mode controls the generation of shadow
  90.      rays through non-opaque objects: 0-none (default), 1-
  91.      partial, 2-full. If a scene has translucent objects, to
  92.      obtain realism one should use 1 or 2 (better).
  93.  
  94.      [mshading-mode]
  95.      The parameter shading-mode chooses between shading models:
  96.      0-normal phong, 1-strauss (default but slower) (note: this
  97.      model was developed by Paul Strauss of SGI).
  98.  
  99.      [nnormal-mode]
  100.      The parameter normal-mode controls the correction of surface
  101.      normals, so that it points against the incident ray: 0-
  102.      always (default), 1-only inside objects. With "correct"
  103.      objects, it is good to use 1.
  104.  
  105.      [znormal-check-mode]
  106.      The parameter normal-check-mode controls the correction of
  107.      surface normals when textures that modify the normal are
  108.      used, as they may sometimes create strange surface effects.
  109.      This tends to happen if the scale of the normal perturbation
  110.      is big.  0-no correction (default), 1-correction.
  111.  
  112.      [Rrawfile]
  113.      The parameter rawfile creates a raw image file, without any
  114.      antialiasing (all defects show up!).
  115.  
  116.      [psampling-levels]
  117.      The parameter sampling-levels controls the amount of sam-
  118.      pling levels inside pixels: 0-none ... 3-maximum (default).
  119.      A reasonable value is 2 for high resolutions, but for small
  120.      ones 3 gives better (and slower) results.
  121.  
  122.      [sshading-levels]
  123.      The parameter shading-levels establishes a maximum shading
  124.      tree depth (default is 8). When a scene has
  125.      transparent/reflective objects, it may be important to lower
  126.      this parameter, or else the tracing never stops. In the
  127.      other cases, there should be no problem allowing it to be
  128.      big.
  129.  
  130.      [ttexture-mode]
  131.      The parameter texture-mode allows the definition of
  132.      texture(s) for the objects: 0-no textures (default), 1-with
  133.      textures defined inside objects field, 2-with textures
  134.      defined after objects field. As textures may consume much
  135.      CPU time, they should be activated only for final images.
  136.  
  137.      [vview-mode]
  138.      The parameter view-mode chooses the view mode: 0-normal
  139.      (default), 1-left eye, 2-right eye.
  140.  
  141.      [Pfocal-aperture]
  142.      The parameter focal-aperture defines the focal aperture of
  143.      the camera (default 0.0, ie, pinhole camera). If different
  144.      than zero, there is depth of field, and so adaptive super-
  145.      sampling antialiasing will not work well.
  146.  
  147.      [Ffocal-distance]
  148.      The parameter focal-distance defines the focal distance of
  149.      the camera (default is the distance from the eye point to
  150.      the look point).
  151.  
  152.      [Estereo-separation]
  153.      The parameter stereo-separation controls the separation
  154.      between the left and the right eye.  If negative, it
  155.      represents a percentage of the gaze distance.
  156.  
  157.      [Ooutput-format]
  158.      The parameter output-format chooses between the PIC format
  159.      (0-default) or the PPM format (1).
  160.  
  161.      [Vverbose-mode]
  162.      The parameter verbose-mode supresses any messages (0) or
  163.      shows listing of parameters (1), previous plus statistics
  164.      (2-default) or previous plus a line by line echo of the
  165.      tracing (3-default on DOS and transputers).
  166.  
  167.      [+Oobjects-max]
  168.      The parameter objects-max defines the maximum number of objects
  169.      to use (default is 25000).
  170.  
  171.      [+Llights-max]
  172.      The parameter lights-max defines the maximum number of lights to
  173.      use (default is 16).
  174.  
  175.      [+Ssurfaces-max]
  176.      The parameter surfaces-max defines the maximum number of surfaces
  177.      to use (default is 256).
  178.  
  179.      [+Ccsg-level-max]
  180.      The parameter csg-level-max defines the maximum number of levels
  181.      in CSG trees to use (default is 256).
  182.  
  183.      [Meeye-file]
  184.      The parameter eye-file is the name of a file that contains eye
  185.      positions for movie fly-throughs (3 real numbers representing XYZ
  186.      in each line). In movie mode, the scene is read only once and
  187.      successive images are produced and stored in the picture file.
  188.  
  189.      [Mllook-file]
  190.      The parameter look-file is the name of a file that contains look
  191.      positions for movie fly-throughs.
  192.  
  193.      [Muup-file]
  194.      The parameter up-file is the name of a file that contains up
  195.      vectors for movie fly-throughs.
  196.  
  197.      [Maangle-file]
  198.      The parameter angle-file is the name of a file that contains
  199.      angle apertures for movie fly-throughs (2 real numbers in each line).
  200.  
  201.      [M+movie-frames-max]
  202.      The parameter movie-frames-max defines the maximum number of frames
  203.      to produce (default is 50).
  204.  
  205.      The scene data internal syntax (SFF) is described bellow.
  206.  
  207.      The image file will contain the ray traced image.  The image
  208.      file has a 4 byte header composed of width LS and MS bytes,
  209.      height LS and MS bytes and RGB byte triplets starting in the
  210.      upper left corner line by line to the lower right corner.
  211.  
  212. RESTRICTIONS
  213.      The straightforward use:
  214.  
  215.        rtrace demo.sff demo.pic
  216.  
  217.      is not recommended, as ray tracing usually takes lots of CPU
  218.      time to execute.
  219.  
  220.      So, it is better to do:
  221.  
  222.        rtrace demo.sff demo.pic >demo.log &
  223.  
  224.      or then use nice (1) or similar strategies.
  225.  
  226. BUGS
  227.      No bugs known.  They have to be hidden deep somewhere, as
  228.      usual.
  229.  
  230. DESCRIPTION
  231.      SFF (Simple File Format) description follows. This is a very
  232.      crude ASCII format, almost like if generated by a lexical
  233.      analyser. The idea is to have other programs create scene
  234.      descriptions in more sophisticated ways, and then feed the
  235.      tokenized results to this program. So, it behaves accord-
  236.      ingly to the UNIX philosophy: one program for one task.
  237.      Complaints are not wellcome!...
  238.  
  239.      There is a reasonable scene language available (SCN) that
  240.      allows the creation of scenes with much more flexibility;
  241.      the converter is called 'scn2sff' and works directly with
  242.      this program.
  243.  
  244.      Note: the ^(circunflex) character represents start of line.
  245.  
  246.      [Start of File]
  247.      ^... Comment
  248.      ^Eye(X Y Z)
  249.      ^Look(X Y Z)
  250.      ^Up(X Y Z)
  251.      ^View_angle(H V) [1,89 degrees]
  252.      ^... Comment
  253.      ^Background(R G B)
  254.      ^Ambient(R G B)
  255.      ^... Comment
  256.      ^Light_type(Type) Position(X Y Z) Bright(R G B) ...
  257.        |                                              |
  258.        |                  /---------------------------/
  259.        |                  |
  260.        V                  V
  261.       1-POINT:
  262.       2-DIRECTIONAL: Direction(X Y Z) Angle(La) Light_Factor(Lf)
  263.       3-EXTENDED:    Radius(R) Samples(N)
  264.      ^Etc
  265.      ^<NL>
  266.      ^... Comment
  267.      ^Surface_type(Type) Color(R G B) ...
  268.        |                               |
  269.        |        /----------------------/
  270.        |        |
  271.        V        V
  272.       1-: Dif(R G B) Spec(R G B) Phong(Pf) Metal(Mf) Trans(R G B)
  273.       2-: Smoothness(R G B) Metalness(R G B) Transmission(R G B)
  274.      ^Etc
  275.      ^<NL>
  276.      ^... Comment
  277.      ^Object_type(Type) Surface_ID(S) Refraction(Re) ...
  278.        |                                              |
  279.        |                     /------------------------/
  280.        |                     |
  281.        V                     V
  282.       1-SPHERE:          Center(X Y Z) Radius(R)
  283.       2-PARALLELIPIPED:  Center(X Y Z) Size(X Y Z)
  284.       3-PATCH:           Origin(X Y Z) Scale(X Y Z) Filename(...)
  285.       4-CONE/CYLINDER:   Base(X Y Z) Base_Radius(Rb) Apex(X Y Z)
  286.                          Apex_Radius(Ra)
  287.       5-POLYGON:         Origin(X Y Z) Scale(X Y Z) Filename(...)
  288.       6-TRIANGLE:        Origin(X Y Z) Scale(X Y Z) Filename(...)
  289.       7-TEXT:            Filename(...)
  290.      or
  291.       64-TEXTURE:        see below
  292.       65-TRANSFORMATION: Object_ID(I)
  293.                          Transform(X1 Y1 Z1 W1 ... X4 Y4 Z4 W4)
  294.       66-CSG 0:          Surface_ID(S) Refraction(Re) (Union-0
  295.      Sub-1 Int-2)
  296.          CSG 1:          Next CSG member
  297.          CSG 2:          End of CSG
  298.       67-LIST 0:         Surface_ID(S) Refraction(Re)
  299.          LIST 1:         End of List
  300.      ^Etc
  301.      ^<NL>
  302.      ^... Comment
  303.      ^Texture_type(Type) Object_ID(I)
  304.        |                 Transform(X1 Y1 Z1 W1 ... X4 Y4 Z4 W4)
  305.        |                 ...
  306.        |                  |
  307.        V                  V
  308.       0-NULL:
  309.       1-CHECKER:   Surface_ID(S)
  310.       2-BLOTCH:    Scale(K) Surface_ID(S) [Filename(...) or -]
  311.       3-BUMP:      Scale(K)
  312.       4-MARBLE:    [Filename(...) or -]
  313.       5-FBM:       Offset(K) Scale(K) Omega(K) Lambda(L)
  314.                    Threshold(K) Octaves(O)
  315.                    [Filename(...) or -]
  316.       6-FBMBUMP:   Offset(K) Scale(K) Lambda(L) Octaves(O)
  317.       7-WOOD:      Color(R G B)
  318.       8-ROUND:     Scale(K)
  319.       9-BOZO:      Turbulence(K) [Filename(...) or -]
  320.       10-RIPPLES:  Frequency(K) Phase(K) Scale(K)
  321.       11-WAVES:    Frequency(K) Phase(K) Scale(K)
  322.       12-SPOTTED:  [Filename(...) or -]
  323.       13-DENTS:    Scale(K)
  324.       14-AGATE:    [Filename(...) or -]
  325.       15-WRINKLES: Scale(K)
  326.       16-GRANITE:  [Filename(...) or -]
  327.       17-GRADIENT: Turbulence(K) Direction(X Y Z)
  328.                    [Filename(...) or -]
  329.       18-IMAGEMAP: Turbulence(K) Mode(K) Axis(X Y) Filename(...)
  330.       19-GLOSS:    Scale(K)
  331.       20-BUMP3:    Scale(K) Size(K)
  332.      ^<NL>
  333.      ^... Comments
  334.      [End of File]
  335.  
  336.      1. Valid ranges of data
  337.  
  338.      RGB must be in [0,1[ (Note: RGB brightness of lights may be
  339.      between ]-300,300[; negative values mean to not attenuate
  340.      with distance).
  341.  
  342.      XYZ must be in [-10000,10000]
  343.  
  344.      Factor must be in [0,300[
  345.  
  346.      Filename must a valid filename for the operating system, or
  347.      then '-', in which case data is read from the standard input
  348.      or the current SFF stream.
  349.  
  350.      2. Patch specification
  351.  
  352.      File format for PATCH (bicubic 4-sided patch):
  353.  
  354.      [Start]
  355.      ^Patch_1_Index(1 2 3 4 5 6 7 8 9 10 11 12)
  356.      ^Patch_2
  357.      ^Etc
  358.      ^<NL>
  359.      ^Patch_Index_1_Coords(X Y Z)
  360.      ^Patch_Index_2_Coords(X Y Z)
  361.      ^Etc
  362.      ^<NL>
  363.      ^...
  364.      [End]
  365.  
  366.      3. Polygon specification
  367.  
  368.      File format for POLYGON (n-sided planar polygon):
  369.  
  370.      [Start]
  371.      ^Polygon_1_Vertex_Number Polygon_1_Index(1 2 3 ...)
  372.      ^Polygon_2
  373.      ^Etc
  374.      ^<NL>
  375.      ^Polygon_Index_1_Coords(X Y Z)
  376.      ^Polygon_Index_2_Coords(X Y Z)
  377.      ^Etc
  378.      ^<NL>
  379.      ^...
  380.      [End]
  381.  
  382.      4. Triangle specification
  383.  
  384.      File format for TRIANGLE (3-sided polygon with vertex nor-
  385.      mals):
  386.  
  387.      [Start]
  388.      ^Triangle_1_Vertice_1(X Y Z) Normal_1(X Y Z)
  389.                  Vertice_2(X Y Z) Normal_2(X Y Z)
  390.                  Vertice_3(X Y Z) Normal_3(X Y Z)
  391.      ^Triangle_2
  392.      ^<NL>
  393.      ^...
  394.      [End]
  395.  
  396.      5. An example
  397.  
  398.      [Start of File]
  399.      View
  400.      25 25 7         - Eye point
  401.      0 0 0           - Look point
  402.      0 1 0           - Up vector
  403.      30 30           - View angles
  404.      Colors
  405.      0.196 0.6 0.8   - Background (Sky Blue)
  406.      0.1 0.1 0.1     - Ambient light
  407.      Lights
  408.      1 0 60 60 0.9 0.9 0.9  - Point Light 1
  409.      1 20 40 -7 0.9 0.9 0.9 - Point Light 2
  410.      <NL>
  411.      Surfaces
  412.      1 0.6 0.8 0.196 0.99 0.99 0.99 0 0 0 0 0 0 0 0
  413.      1 0.9 0.9 0.9 0.5 0.5 0.5 0.5 0.5 0.5 50 1 0 0 0
  414.      1 0.5 0.5 0.5 0.1 0.1 0.1 0.1 0.1 0.1 200 0.7 0.8 0.8 0.8
  415.      1 0.9 0.2 0.2 0.99 0.99 0.99 0 0 0 0 0 0 0 0
  416.      <NL>
  417.      Objects
  418.      5 1 1.0 0 0 0 15 15 15  - Polygon
  419.      4 1 2 3 4
  420.      <NL>
  421.      1 0 1
  422.      1 0 -1
  423.      -1 0 -1
  424.      -1 0 1
  425.      <NL>
  426.      2 2 1.0 0 2 0 7 2 3     - Parallelipiped
  427.      2 3 1.5 0 5 10 3 5 3    - Parallelipiped
  428.      1 4 1.0 7 15 -7 3       - Sphere
  429.      <NL>
  430.      Textures
  431.      2 1 2 0 0 0 0 2 0 0 0 0 2 0 0 0 0 1 0.4 4
  432.      4 2 5 0 0 0 0 5 0 0 0 0 5 0 0 0 0 1
  433.      5 4 10 0 0 0 1 10 0 0 1 1 10 0 0 0 0 1 0 0.6 0.5 2 0.1 6
  434.      <NL>
  435.      Demo / 11-OCT-1989 / Antonio Costa
  436.      [End of File]
  437.  
  438.      To ray trace without textures, do:
  439.  
  440.        rtrace demo.sff demo.pic >&demo.log
  441.  
  442.      else, do:
  443.  
  444.        rtrace t2 demo.sff demo.pic >&demo.log
  445.  
  446.      Another example with INESC symbol:
  447.  
  448.      [Start of File]
  449.      View
  450.      45.0 45.0 81.0  - Eye point
  451.      45.0 45.0 -81.0 - Look point
  452.       0.0  1.0  0.0  - Up vector
  453.      30 30           - View angles
  454.      Colors
  455.      0.196 0.6 0.8 - Background (Sky Blue)
  456.      0.3 0.3 0.3   - Ambient
  457.      Lights
  458.      1  0.0 100.0 100.0 1 1 1 - Light 1 (White)
  459.      1 90.0 100.0 100.0 1 1 0 - Light 2 (Yellow)
  460.      <NL>
  461.      Surfaces
  462.      1 0.557 0.420 0.137 0.8 0.7 0.7 0.2 0.3 0.3 30 0.8 0 0 0
  463.      1 0.137 0.420 0.557 0.5 0.5 0.6 0.5 0.5 0.4 5 0.2 0 0 0
  464.      1 0.600 0.800 0.200 0.9 0.9 0.9 0.0 0.0 0.0 1 0 0 0 0
  465.      <NL>
  466.      Objects
  467.      1 1 1.0 10.0 09.5 0.0 4.5 - Sphere
  468.      1 1 1.0 10.0 26.5 0.0 4.5
  469.      1 1 1.0 20.0 63.5 0.0 4.5
  470.      1 1 1.0 20.0 80.0 0.0 4.5
  471.      1 1 1.0 40.0 09.5 0.0 4.5
  472.      1 1 1.0 40.0 26.5 0.0 4.5
  473.      1 1 1.0 40.0 43.5 0.0 4.5
  474.      1 1 1.0 50.0 80.0 0.0 4.5
  475.      1 1 1.0 60.0 53.0 0.0 4.5
  476.      1 1 1.0 70.0 09.5 0.0 4.5
  477.      1 1 1.0 70.0 43.5 0.0 4.5
  478.      4 2 1.0 10.0 30.0 0.0 1.5 10.0 70.0 0.0 1.5 - Cylinder
  479.      1 2 1.0 10.0 70.0 0.0 1.5
  480.      4 2 1.0 10.0 70.0 0.0 1.5 17.5 77.5 0.0 1.5
  481.      4 2 1.0 12.5 12.0 0.0 1.5 20.0 19.5 0.0 1.5
  482.      1 2 1.0 20.0 19.5 0.0 1.5
  483.      4 2 1.0 20.0 19.5 0.0 1.5 20.0 60.0 0.0 1.5
  484.      4 2 1.0 22.5 61.0 0.0 1.5 37.5 46.0 0.0 1.5
  485.      4 2 1.0 37.5 12.0 0.0 1.5 30.0 19.5 0.0 1.5
  486.      1 2 1.0 30.0 19.5 0.0 1.5
  487.      4 2 1.0 30.0 19.5 0.0 1.5 30.0 33.5 0.0 1.5
  488.      1 2 1.0 30.0 33.5 0.0 1.5
  489.      4 2 1.0 30.0 33.5 0.0 1.5 37.5 41.0 0.0 1.5
  490.      4 2 1.0 30.0 26.5 0.0 1.5 36.5 26.5 0.0 1.5
  491.      4 2 1.0 40.0 47.0 0.0 1.5 40.0 70.0 0.0 1.5
  492.      1 2 1.0 40.0 70.0 0.0 1.5
  493.      4 2 1.0 40.0 70.0 0.0 1.5 47.5 77.5 0.0 1.5
  494.      4 2 1.0 42.5 12.0 0.0 1.5 50.0 19.5 0.0 1.5
  495.      1 2 1.0 50.0 19.5 0.0 1.5
  496.      4 2 1.0 50.0 19.5 0.0 1.5 50.0 43.0 0.0 1.5
  497.      1 2 1.0 50.0 43.0 0.0 1.5
  498.      4 2 1.0 50.0 43.0 0.0 1.5 57.5 50.5 0.0 1.5
  499.      4 2 1.0 67.5 12.0 0.0 1.5 60.0 19.5 0.0 1.5
  500.      1 2 1.0 60.0 19.5 0.0 1.5
  501.      4 2 1.0 60.0 19.5 0.0 1.5 60.0 33.5 0.0 1.5
  502.      1 2 1.0 60.0 33.5 0.0 1.5
  503.      4 2 1.0 60.0 33.5 0.0 1.5 67.5 41.0 0.0 1.5
  504.      5 3 1.0 0.0 4.0 0.0 200.0 200.0 200.0 - Polygon
  505.      4 1 2 3 4
  506.      <NL>
  507.       1.0 0.0  1.0
  508.       1.0 0.0 -1.0
  509.      -1.0 0.0 -1.0
  510.      -1.0 0.0  1.0
  511.      <NL>
  512.      <NL>
  513.      End
  514.      INESC Logo / 23-FEB-1989 / Antonio Costa
  515.  
  516. HISTORY
  517.      Copyright (C) 1988 1992 by Antonio Costa.
  518.      Permission is granted to use this file in whole or in part
  519.      for any purpose, educational, recreational or commercial,
  520.      provided that this copyright notice is retained unchanged.
  521.      This software is available to all free of charge by
  522.      anonymous FTP.
  523.  
  524.      08-Sep-92  Antonio Costa at INESC-Norte
  525.           Release 8.0.0
  526.           acc@asterix.inescn.pt acc@basinger.inescn.pt
  527.